macaliasrecord.htmlHTMLudogE4πùΔ£πùΔ£ÅÅ˘3 Monkeybread Realbasic plugin - Documentation - MacAliasRecord

MBS Plugin Documentation

This is the documentation for the Realbasic Plugins from Monkeybreadsoftware.de. You find these plugins and the newest version of this document at http://www.monkeybreadsoftware.de/realbasic inside the plugins section.

This help was last updated on Freitag, 6. September 2002 and covers 2136 items: 126 classes, 2 controls and 583 global functions.

The list of the themes Global methods by category Global methods by name The list of the classes The list of the controls

class MacAliasRecord
class, Alias Mo, 15. Jul 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: does nothing.
Function: Gives access to Aliases on Mac.
Example:
' Store the reference to a FolderItem in a Binary File

Dim alias as MacAliasRecord, f as FolderItem
Dim bf as BinaryStream, s as String
f = ... // the FolderItem you want to save
bf = ... // open your binary file here
alias = new MacAliasRecord
if alias.Create(nil, f) = 0 then
s = alias.GetRecord()
bf.WriteLong LenB(s) // this saves the length of the record
bf.Write s // this saves the record itself
end

' Retrieve the reference to a FolderItem from a Binary File

Dim alias as MacAliasRecord, f as FolderItem
Dim bf as BinaryStream, l as Integer
bf = ... // open your binary file here
alias = new MacAliasRecord
l = bf.ReadLong
alias.SetRecord bf.Read(l)
f = alias.Resolve(nil, alias.attemptMount)
if alias.needsUpdate then
if alias.Update(nil, f) = 1 then
... you might want to save the updated alias in your file here
end
end
// f now describes the FolderItem again.
// It may not be existing any more, however, so here's a check for that:
if not f.exists then
msgBox "oops! the file is not available any more. Select a new one, please"
... let the user locate the file
end


Notes:
This Plugin implements a new Class for handling Mac OS Alias Records.

AliasRecords are like FolderItems, but can be made persistent: You can convert a FolderItem into a AliasRecord and store that AliasRecord in a file (like your Preferences file). Later you can retrieve that information again and convert it back into a FolderItem.

AliasRecords also appear inside Alias Files, that are usually created by the Finder. The enclosed sample application (Alias Mgr Plugin Demo.π) shows how to create and resolve such Alias Files.

Additional Background Information
The purpose of the class is to store paths to files and/or folders between runs of a RB application.
To store a path to a file/folder in an RB app, currently your only option is to get the abolute path as a string, and store that string in a file, usually your preferences file.
However, there is problem with using this technique: If, between runs of your app, the user changes the path of the file by moving it, or by renaming the file or any of its parent folders (including the volume name), your app will fail to locate the file next time
it is looking for it.
Fortunately, at least in Mac OS, there's a solution to this, which helps you to track your files in such a case. This is done by using Alias Records: they are the basic data structure that is also used in Alias Files as created and used in the Finder.
This class attempts to give the flexibility of Alias Records to your RB apps.

The meaning of the Relative path
When no relative path is specified, then the file is only located by its folder hierarchy down to the root of the volume. However, if a relative path is given, then the file is optionally located relative to that point.
So, if you locate files relatively to some folder, like the folder your application is in, you should specify your app's folder as the relative path so that the target is even found easily when the user moved the whole folder including your app and its related files. This is even more important when using this Alias class under Windows than under Mac OS (if files are moved in Mac OS, they often still can be found even without the help of the original folder hierarchy, while this is not possible under Windows 9x).

allVols=8
const, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: Works
Function: constant for use with Resolve.

attemptMount=1
const, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: Works
Function:
constant for use with Resolve:
attempts to mount a volume when it is not available (like network volumes and removable disks).

Create(relPath as FolderItem, target as FolderItem) as Integer
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Creates an AliasRecord for a given file or folder. Returns zero if successful, otherwise a negative Mac OS error code.

CreateMinimal(target as FolderItem) as Integer
method, Alias So, 21. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Creates an AliasRecord for a given file or folder. Returns zero if successful, otherwise a negative Mac OS error code.
Notes: Minimal creates an alias without path, so it's smaller.

exhaustive=512
const, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: Works
Function: constant for use with Resolve.

GetInfo(idx as Integer) as String
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Returns information about the AliasRecord, without resolving it (no disk access will happen).
Notes:
Possible values for "idx":
-3returns the Network Zone Name, if any.
-2returns the Network Server Name, if any.
-1returns the Volume Name.
0returns the Item Name.
1 and higherreturns the parent directories of the item.

GetRecord() as String
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Returns the AliasRecord in a String so that you can store it in a file, and pass it SetRecord for re-creating the AliasRecord (this string might contain any byte values, including zeros, so you can not display it or store it in a text file - you have to store it in a binary file or in a resource, instead!).
Notes: Attention: The length of the String is not fixed! When the Alias changes, its length usually changes, too. If you want to save this string into a binary file, you must also save its current length so that you know how much bytes to retrieve if you read it back from the file later. An easier way to store Aliases in a file is by using the Resource Manager. The sample code "FolderItems in Preferences.rbp" shows how to accomplish this.

needsUpdate as boolean
property, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Does the Alias Record need no Update?
Notes:
after having called Resolve successfullly, this property indicates whether the AliasRecord is still up to date:
true: the target of the Alias is still at the same location where it was last seen.
false: the target has been moved or renamed. The Update method should be invoked.

noDialogs=2
const, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: Works
Function:
constant for use with Resolve:
suppresses any user interaction, like network login dialogs and disk insertion prompts. Only relevant if attemptMount is used.

relFirst=1024
const, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: Works
Function:
constant for use with Resolve:
if a relative path is given, this argument lets Resolve do a relative search before a absolute search. Without this argument, a relative search is only performed if the target is not found at its orginal absolute position.

Resolve(relPath as FolderItem, mode as Integer) as FolderItem
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Converts an AliasRecord back into a FolderItem. For values to the mode parameter see the Properties below or pass in 0 for default searching (will not attempt to mount unavailable volumes).
Notes: After calling this method, the property needsUpdate tells you whether the target has been renamed or moved, which suggests that you call Update in order to reflect the change in the AliasRecord. See the demo "FolderItems in Preferences.rbp" for an example.

SetRecord(record as String)
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Use this method to revive an AliasRecord with the string you inquired from GetRecord earlier.

Update(relPath as FolderItem, target as FolderItem) as Integer
method, Alias Mo, 15. Jul 2002
Mac OS Classic: Works Mac OS Carbon: Works Windows: does nothing.
Function: Updates an already created AliasRecord. Returns either a negative Mac OS error code, zero if the update didn't actually change the AliasRecord, or one if the record was changed (in this case you might want to update your record of the alias if you had stored it in a file).

Contact

Written 2002 by Christian Schmitz. Feel free to ask or report mistakes to realbasic@macsw.de.
Thanks.

This resource fork intentionally left blank ˇˇ